home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3n / t_alloc.z / t_alloc
Encoding:
Text File  |  2002-10-03  |  10.1 KB  |  133 lines
  1.  
  2.  
  3.  
  4. tttt____aaaalllllllloooocccc((((3333NNNN))))                                                        tttt____aaaalllllllloooocccc((((3333NNNN))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _tttt______aaaa_llll_llll_oooo_cccc - allocate a library structure
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_ffff_dddd_eeee_ffff ______XXXX_OOOO_PPPP_EEEE_NNNN______SSSS_OOOO_UUUU_RRRR_CCCC_EEEE
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_xxxx_tttt_iiii_...._hhhh_>>>>
  14.      _####_eeee_llll_ssss_eeee
  15.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_tttt_iiii_uuuu_ssss_eeee_rrrr_...._hhhh_>>>>
  16.      _####_eeee_nnnn_dddd_iiii_ffff
  17.  
  18.      _cccc_hhhh_aaaa_rrrr _****_tttt______aaaa_llll_llll_oooo_cccc_((((_ffff_dddd_,,,, _ssss_tttt_rrrr_uuuu_cccc_tttt______tttt_yyyy_pppp_eeee_,,,, _ffff_iiii_eeee_llll_dddd_ssss_))))
  19.      _iiii_nnnn_tttt _ffff_dddd_;;;;
  20.      _iiii_nnnn_tttt _ssss_tttt_rrrr_uuuu_cccc_tttt______tttt_yyyy_pppp_eeee_;;;;
  21.      _iiii_nnnn_tttt _ffff_iiii_eeee_llll_dddd_ssss_;;;;
  22.  
  23. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  24.      The _tttt______aaaa_llll_llll_oooo_cccc function dynamically allocates memory for the various
  25.      transport function argument structures as specified below.  This function
  26.      will allocate memory for the specified structure, and will also allocate
  27.      memory for buffers referenced by the structure.
  28.  
  29.      The structure to allocate is specified by _ssss_tttt_rrrr_uuuu_cccc_tttt______tttt_yyyy_pppp_eeee, and can be one of
  30.      the following:
  31.  
  32.      _TTTT______BBBB_IIII_NNNN_DDDD           _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______bbbb_iiii_nnnn_dddd
  33.  
  34.      _TTTT______CCCC_AAAA_LLLL_LLLL           _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______cccc_aaaa_llll_llll
  35.  
  36.      _TTTT______OOOO_PPPP_TTTT_MMMM_GGGG_MMMM_TTTT        _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______oooo_pppp_tttt_mmmm_gggg_mmmm_tttt
  37.  
  38.      _TTTT______DDDD_IIII_SSSS            _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______dddd_iiii_ssss_cccc_oooo_nnnn
  39.  
  40.      _TTTT______UUUU_NNNN_IIII_TTTT_DDDD_AAAA_TTTT_AAAA       _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______uuuu_nnnn_iiii_tttt_dddd_aaaa_tttt_aaaa
  41.  
  42.      _TTTT______UUUU_DDDD_EEEE_RRRR_RRRR_OOOO_RRRR        _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______uuuu_dddd_eeee_rrrr_rrrr
  43.  
  44.      _TTTT______IIII_NNNN_FFFF_OOOO           _ssss_tttt_rrrr_uuuu_cccc_tttt _tttt______iiii_nnnn_ffff_oooo
  45.  
  46.      where each of these structures may subsequently be used as an argument to
  47.      one or more transport functions.
  48.  
  49.      Each of the above structures, except _TTTT______IIII_NNNN_FFFF_OOOO, contains at least one field
  50.      of type _ssss_tttt_rrrr_uuuu_cccc_tttt _nnnn_eeee_tttt_bbbb_uuuu_ffff.  _nnnn_eeee_tttt_bbbb_uuuu_ffff is described in _iiii_nnnn_tttt_rrrr_oooo(3N).  For each field
  51.      of this type, the user may specify that the buffer for that field should
  52.      be allocated as well.  The _ffff_iiii_eeee_llll_dddd_ssss argument specifies this option, where
  53.      the argument is the bitwise-_OOOO_RRRR of any of the following:
  54.  
  55.      _TTTT______AAAA_DDDD_DDDD_RRRR    The _aaaa_dddd_dddd_rrrr field of the _tttt______bbbb_iiii_nnnn_dddd, _tttt______cccc_aaaa_llll_llll, _tttt______uuuu_nnnn_iiii_tttt_dddd_aaaa_tttt_aaaa, or _tttt______uuuu_dddd_eeee_rrrr_rrrr
  56.                structures.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. tttt____aaaalllllllloooocccc((((3333NNNN))))                                                        tttt____aaaalllllllloooocccc((((3333NNNN))))
  71.  
  72.  
  73.  
  74.      _TTTT______OOOO_PPPP_TTTT     The _oooo_pppp_tttt field of the _tttt______oooo_pppp_tttt_mmmm_gggg_mmmm_tttt, _tttt______cccc_aaaa_llll_llll, _tttt______uuuu_nnnn_iiii_tttt_dddd_aaaa_tttt_aaaa, or _tttt______uuuu_dddd_eeee_rrrr_rrrr
  75.                structures.
  76.  
  77.      _TTTT______UUUU_DDDD_AAAA_TTTT_AAAA   The _uuuu_dddd_aaaa_tttt_aaaa field of the _tttt______cccc_aaaa_llll_llll, _tttt______dddd_iiii_ssss_cccc_oooo_nnnn, or _tttt______uuuu_nnnn_iiii_tttt_dddd_aaaa_tttt_aaaa
  78.                structures.
  79.  
  80.      _TTTT______AAAA_LLLL_LLLL     All relevant fields of the given structure.
  81.  
  82.      For each field specified in _ffff_iiii_eeee_llll_dddd_ssss, _tttt______aaaa_llll_llll_oooo_cccc will allocate memory for the
  83.      buffer associated with the field, and initialize the _bbbb_uuuu_ffff pointer and
  84.      _mmmm_aaaa_xxxx_llll_eeee_nnnn [see _nnnn_eeee_tttt_bbbb_uuuu_ffff in _iiii_nnnn_tttt_rrrr_oooo(3N) for description of _bbbb_uuuu_ffff and _mmmm_aaaa_xxxx_llll_eeee_nnnn] field
  85.      accordingly.  The length of the buffer allocated will be based on the
  86.      same size information that is returned to the user on _tttt______oooo_pppp_eeee_nnnn and
  87.      _tttt______gggg_eeee_tttt_iiii_nnnn_ffff_oooo.  Thus, _ffff_dddd must refer to the transport endpoint through which
  88.      the newly allocated structure will be passed, so that the appropriate
  89.      size information can be accessed.  If the size value associated with any
  90.      specified field is -1 or -2 (see _tttt______oooo_pppp_eeee_nnnn or _tttt______gggg_eeee_tttt_iiii_nnnn_ffff_oooo), _tttt______aaaa_llll_llll_oooo_cccc will be
  91.      unable to determine the size of the buffer to allocate and will fail,
  92.      setting _tttt______eeee_rrrr_rrrr_nnnn_oooo to _TTTT_SSSS_YYYY_SSSS_EEEE_RRRR_RRRR and _eeee_rrrr_rrrr_nnnn_oooo to _EEEE_IIII_NNNN_VVVV_AAAA_LLLL.  For any field not
  93.      specified in _ffff_iiii_eeee_llll_dddd_ssss, _bbbb_uuuu_ffff will be set to _NNNN_UUUU_LLLL_LLLL and _mmmm_aaaa_xxxx_llll_eeee_nnnn will be set to
  94.      zero.
  95.  
  96.      Use of _tttt______aaaa_llll_llll_oooo_cccc to allocate structures will help ensure the compatibility
  97.      of user programs with future releases of the transport interface.
  98.  
  99.      This function resides within both the X/Open compliant _llll_iiii_bbbb_xxxx_nnnn_eeee_tttt and the
  100.      SVR4 compliant _llll_iiii_bbbb_nnnn_ssss_llll Network Services libraries.  Network Services
  101.      applications which require X/Open compliance must link-load with _----_llll_xxxx_nnnn_eeee_tttt.
  102.      Network Services applications which require SVR4 compliance must link-
  103.      load with _----_llll_nnnn_ssss_llll.
  104.  
  105.      On failure, _tttt______eeee_rrrr_rrrr_nnnn_oooo may be set to one of the following:
  106.  
  107.      _TTTT_BBBB_AAAA_DDDD_FFFF          The specified file descriptor does not refer to a
  108.                     transport endpoint.
  109.  
  110.      _TTTT_SSSS_YYYY_SSSS_EEEE_RRRR_RRRR        A system error has occurred during execution of this
  111.                     function.
  112.  
  113.      _TTTT_NNNN_OOOO_SSSS_TTTT_RRRR_UUUU_CCCC_TTTT_YYYY_PPPP_EEEE   Unsupported _ssss_tttt_rrrr_uuuu_cccc_tttt______tttt_yyyy_pppp_eeee requested.  This can include a
  114.                     request for a structure type which is inconsistent with
  115.                     the transport provider type specified, that is,
  116.                     connection-oriented or connectionless.
  117.  
  118. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  119.      _iiii_nnnn_tttt_rrrr_oooo(3N), _tttt______ffff_rrrr_eeee_eeee(3N), _tttt______gggg_eeee_tttt_iiii_nnnn_ffff_oooo(3N), _tttt______oooo_pppp_eeee_nnnn(3N)
  120.  
  121. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  122.      On successful completion, _tttt______aaaa_llll_llll_oooo_cccc returns a pointer to the newly
  123.      allocated structure.  On failure, _NNNN_UUUU_LLLL_LLLL is returned.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.